<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Transform - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The Transform command performs miscellaneous math functions, bitwise operations, and tasks such as ASCII/Unicode conversion." />
<meta name="ahk:equiv-v2" content="commands/Math.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Transform</h1>

<p>Performs miscellaneous math functions, bitwise operations, and tasks such as ASCII/Unicode conversion.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, <a href="#SubCommands">SubCommand</a>, Value1 <span class="optional">, Value2</span></pre>
<p>The <em>OutputVar</em> parameter is the name of the variable in which to store the result. The <em>SubCommand</em>, <em>Value1</em> and <em>Value2</em> parameters are dependent upon each other and their usage is described below.</p>

<h2 id="SubCommands">Sub-commands</h2>
<p>For <em>SubCommand</em>, specify one of the following:</p>
<ul>
  <li><a href="#Unicode">Unicode</a> (for ANSI builds only): Retrieves or stores Unicode text on the clipboard.</li>
  <li><a href="#Deref">Deref</a>: Expands variable references and escape sequences contained inside other variables.</li>
  <li><a href="#HTML">HTML</a>: Converts the specified string into its HTML equivalent.</li>
</ul>
<p><strong>Deprecated</strong> (has a more concise function or operator):</p>
<ul>
  <li><a href="#Asc">Asc</a>: Retrieves the character code for the first character in the specified string.</li>
  <li><a href="#Chr">Chr</a>: Retrieves the single character corresponding to the character code.</li>
  <li><a href="#Mod">Mod</a>: Retrieves the remainder of a division.</li>
  <li><a href="#Exp">Exp</a>: Retrieves e raised to the <em>N</em>th power.</li>
  <li><a href="#Sqrt">Sqrt</a>: Retrieves the square root of a number.</li>
  <li><a href="#Log">Log</a>: Retrieves the logarithm (base 10) of a number.</li>
  <li><a href="#Ln">Ln</a>: Retrieves the natural logarithm (base e) of a number.</li>
  <li><a href="#Round">Round</a>: Retrieves a number rounded to <em>N</em> decimal places.</li>
  <li><a href="#Ceil">Ceil</a>: Retrieves a number rounded up to the nearest integer.</li>
  <li><a href="#Floor">Floor</a>: Retrieves a number rounded down to the nearest integer.</li>
  <li><a href="#Abs">Abs</a>: Retrieves the absolute value of a number.</li>
  <li><a href="#Sin">Sin</a>: Retrieves the trigonometric sine of a number.</li>
  <li><a href="#Cos">Cos</a>: Retrieves the trigonometric cosine of a number.</li>
  <li><a href="#Tan">Tan</a>: Retrieves the trigonometric tangent of a number.</li>
  <li><a href="#ASin">ASin</a>: Retrieves the arcsine in radians.</li>
  <li><a href="#ACos">ACos</a>: Retrieves the arccosine in radians.</li>
  <li><a href="#ATan">ATan</a>: Retrieves the arctangent in radians.</li>
  <li><a href="#Pow">Pow</a>: Retrieves a base raised to the power of an exponent.</li>
  <li><a href="#BitNot">BitNot</a>: Retrieves the bit-inverted version of a number.</li>
  <li><a href="#BitAnd">BitAnd</a>: Retrieves the result of the bitwise-AND of the specified numbers.</li>
  <li><a href="#BitOr">BitOr</a>: Retrieves the result of the bitwise-OR of the specified numbers.</li>
  <li><a href="#BitXOr">BitXOr</a>: Retrieves the result of the bitwise-EXCLUSIVE-OR of the specified numbers.</li>
  <li><a href="#BitShiftLeft">BitShiftLeft</a>: Retrieves the result of shifting a number to the left by <em>N</em> bit positions.</li>
  <li><a href="#BitShiftRight">BitShiftRight</a>: Retrieves the result of shifting a number to the right by <em>N</em> bit positions.</li>
</ul>

<h3 id="Unicode">Unicode</h3>
<p>Retrieves or stores Unicode text on the clipboard (for ANSI builds only).</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Unicode <span class="optional">, String</span></pre>
<p>Note: The entire clipboard may be saved and restored by means of <a href="../misc/Clipboard.htm#ClipboardAll">ClipboardAll</a>, which allows this sub-command to operate without losing the original contents of the clipboard.</p>
<p>There are two modes of operation as illustrated in the following examples:</p>
<pre>Transform, OutputVar, Unicode  <em>; Retrieves the clipboard's Unicode text as a UTF-8 string.</em>
Transform, Clipboard, Unicode, %MyUTF_String%  <em>; Places Unicode text onto the clipboard.</em></pre>
<p>In the second example above, a literal UTF-8 string may be optionally used in place of <code>%MyUTF_String%</code>.</p>
<p>Use a hotkey such as the following to determine the UTF-8 string that corresponds to a given Unicode string:</p>
<pre>^!u::  <em>; Control+Alt+U hotkey.</em>
MsgBox Copy some Unicode text onto the clipboard, then return to this window and press OK to continue.
Transform, ClipUTF, Unicode
Clipboard := "Transform, Clipboard, Unicode, %ClipUTF%`r`n"
MsgBox The clipboard now contains the following line that you can paste into your script. When executed, this line will cause the original Unicode string you copied to be placed onto the clipboard:`n`n%Clipboard%
return</pre>
<p class="note"><strong>Note:</strong> The <code><a href="Send.htm#sendu">Send {U+nnnn}</a></code> command is an alternate way to produce Unicode characters.</p>

<h3 id="Deref">Deref</h3>
<p>Expands variable references and <a href="_EscapeChar.htm">escape sequences</a> contained inside other variables.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Deref, String</pre>
<p>Any badly formatted variable references will be omitted from the expanded result. The same is true if <em>OutputVar</em> is expanded into itself; in other words, any references to <em>OutputVar</em> inside <em>String's</em> variables will be omitted from the expansion (note however that <em>String</em> <strong>itself</strong> can be <code>%OutputVar%</code>). In the following example, if Var1 contains the string &quot;test&quot; and Var2 contains the <strong>literal</strong> string &quot;%Var1%&quot;, <em>OutputVar</em> will be set to the string &quot;test&quot;: <code>Transform, OutputVar, Deref, %Var2%</code>. Within a <a href="../Functions.htm">function</a>, each variable in <em>String</em> always resolves to a local variable unless there is no such variable, in which case it resolves to a global variable (or blank if none).</p>

<h3 id="HTML">HTML</h3>
<p>Converts <em>String</em> into its HTML equivalent by translating characters whose ASCII values are above 127 to their HTML names (e.g. <code>&pound;</code> becomes <code>&amp;pound;</code>).</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, HTML, String <span class="optional">, Flags</span></pre>
<p>In addition, the four characters <code>&quot;&amp;&lt;&gt;</code> are translated to <code>&amp;quot;&amp;amp;&amp;lt;&amp;gt;</code>. Finally, each linefeed (<code>`n</code>) is translated to <code>&lt;br&gt;`n</code> (i.e. <code>&lt;br&gt;</code> followed by a linefeed). The <em>Flags</em> parameter is ignored.</p>
<p><strong>For Unicode executables:</strong> In addition of the functionality above, <em>Flags</em> can be zero or a combination (sum) of the following values. If omitted, it defaults to 1.</p>
<ul>
<li>1: Converts certain characters to named expressions. e.g. <code>&euro;</code> is converted to <code>&amp;euro;</code></li>
<li>2: Converts certain characters to numbered expressions. e.g. <code>&#8364;</code> is converted to <code>&amp;#8364;</code></li>
</ul>
<p>Only non-ASCII characters are affected. If <i>Flags</i> is the number 3, numbered expressions are used only where a named expression is not available. The following characters are always converted: <code>&lt;&gt;&quot;&amp;</code> and <code>`n</code> (line feed).</p>

<h3 id="Asc">Asc</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Asc.htm">Asc()</a> instead.</p>
<p>Retrieves the character code (a number between 1 and 255, or 1 and 65535 if Unicode is supported) for the first character in <em>String</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Asc, String</pre>
<p>If <em>String</em> is empty, <em>OutputVar</em> will also be made empty. For example: <code>Transform, OutputVar, Asc, %VarContainingString%</code>. To allow for Unicode supplementary characters, use <a href="Ord.htm">Ord()</a> instead.</p>

<h3 id="Chr">Chr</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Chr.htm">Chr()</a> instead.</p>
<p>Retrieves the single character corresponding to the character code indicated by <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Chr, Number</pre>
<p>If <em>Number</em> is not between 1 and 255 inclusive (or 1 and 65535 if Unicode is supported), <em>OutputVar</em> will be made blank to indicate the problem. For example: <code>Transform, OutputVar, Chr, 130</code>. Unlike <a href="Chr.htm">Chr()</a>, this sub-command does not support Unicode supplementary characters (character codes 0x10000 to 0x10FFFF).</p>

<h3 id="Mod">Mod</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Mod">Mod()</a> instead.</p>
<p>Retrieves the remainder of <em>Dividend</em> divided by <em>Divisor</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Mod, Dividend, Divisor</pre>
<p>If <em>Divisor</em> is zero, <em>OutputVar</em> will be made blank. <em>Dividend</em> and <em>Divisor</em> can both contain a decimal point. If negative, <em>Divisor</em> will be treated as positive for the calculation. In the following example, the result is 2: <code>Transform, OutputVar, Mod, 5, 3</code>.</p>

<h3 id="Exp">Exp</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Exp">Exp()</a> instead.</p>
<p>Retrieves e (which is approximately 2.71828182845905) raised to the <em>N</em>th power.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Exp, N</pre>
<p><em>N</em> may be negative and may contain a decimal point.</p>

<h3 id="Sqrt">Sqrt</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Sqrt">Sqrt()</a> instead.</p>
<p>Retrieves the square root of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Sqrt, Number</pre>
<p>If <em>Number</em> is negative, <em>OutputVar</em> will be made blank.</p>

<h3 id="Log">Log</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Log">Log()</a> instead.</p>
<p>Retrieves the logarithm (base 10) of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Log, Number</pre>
<p>If <em>Number</em> is negative, <em>OutputVar</em> will be made blank.</p>

<h3 id="Ln">Ln</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Ln">Ln()</a> instead.</p>
<p>Retrieves the natural logarithm (base e) of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Ln, Number</pre>
<p>If <em>Number</em> is negative, <em>OutputVar</em> will be made blank.</p>

<h3 id="Round">Round</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Round">Round()</a> instead.</p>
<p>Retrieves <em>Number</em> rounded to <em>N</em> decimal places.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Round, Number <span class="optional">, N</span></pre>
<p>If <em>N</em> is omitted, <em>OutputVar</em> will be set to <em>Number</em> rounded to the nearest integer. If <em>N</em> is positive number, <em>Number</em> will be rounded to <em>N</em> decimal places. If <em>N</em> is negative, <em>Number</em> will be rounded by <em>N</em> digits to the left of the decimal point. For example, -1 rounds to the ones place, -2 rounds to the tens place, and-3 rounds to the hundreds place. Note: The Round sub-command does not remove trailing zeros when rounding decimal places. For example, 12.333 rounded to one decimal place would become 12.300000. This behavior can be altered by using something like <code><a href="SetFormat.htm">SetFormat</a>, Float, 0.1</code> prior to the operation (in fact, <a href="SetFormat.htm">SetFormat</a> might eliminate the need to use the Round sub-command in the first place).</p>

<h3 id="Ceil">Ceil</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Ceil">Ceil()</a> instead.</p>
<p>Retrieves <em>Number</em> rounded up to the nearest integer.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Ceil, Number</pre>

<h3 id="Floor">Floor</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Floor">Floor()</a> instead.</p>
<p>Retrieves <em>Number</em> rounded down to the nearest integer.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Floor, Number</pre>

<h3 id="Abs">Abs</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Abs">Abs()</a> instead.</p>
<p>Retrieves the absolute value of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Abs, Number</pre>
<p>This is computed by removing the leading minus sign (dash) from <em>Number</em> if it has one.</p>

<h3 id="Sin">Sin</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Sin">Sin()</a> instead.</p>
<p>Retrieves the trigonometric sine of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Sin, Number</pre>
<p><em>Number</em> must be expressed in radians.</p>

<h3 id="Cos">Cos</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Cos">Cos()</a> instead.</p>
<p>Retrieves the trigonometric cosine of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Cos, Number</pre>
<p><em>Number</em> must be expressed in radians.</p>

<h3 id="Tan">Tan</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#Tan">Tan()</a> instead.</p>
<p>Retrieves the trigonometric tangent of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Tan, Number</pre>
<p><em>Number</em> must be expressed in radians.</p>

<h3 id="ASin">ASin</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#ASin">ASin()</a> instead.</p>
<p>Retrieves the arcsine (the number whose sine is <em>Number</em>) in radians.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, ASin, Number</pre>
<p>If <em>Number</em> is less than -1 or greater than 1, <em>OutputVar</em> will be made blank.</p>

<h3 id="ACos">ACos</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#ACos">ACos()</a> instead.</p>
<p>Retrieves the arccosine (the number whose cosine is <em>Number</em>) in radians.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, ACos, Number</pre>
<p>If <em>Number</em> is less than -1 or greater than 1, <em>OutputVar</em> will be made blank.</p>

<h3 id="ATan">ATan</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use <a href="Math.htm#ATan">ATan()</a> instead.</p>
<p>Retrieves the arctangent (the number whose tangent is <em>Number</em>) in radians.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, ATan, Number</pre>

<h3 id="Pow">Pow</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#pow"><code>**</code> operator</a> instead.</p>
<p>Retrieves <em>Base</em> raised to the power of <em>Exponent</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, Pow, Base, Exponent</pre>
<p>Both <em>Base</em> and <em>Exponent</em> may contain a decimal point. If <em>Exponent</em> is negative, <em>OutputVar</em> will be formatted as a floating point number even if <em>Base</em> and <em>Exponent</em> are both integers. A negative <em>Base</em> combined with a fractional <em>Exponent</em> such as 1.5 is not supported; it will cause <em>OutputVar</em> to be made blank.</p>

<h3 id="BitNot">BitNot</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#unary"><code>~</code> operator</a> instead.</p>
<p>Retrieves the bit-inverted version of <em>Number</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitNot, Number</pre>
<p>Floating point values are truncated to integers prior to the calculation. If <em>Number</em> is between 0 and 4294967295 (0xffffffff), it will be treated as an <strong>unsigned</strong> 32-bit value. Otherwise, it is treated as a <strong>signed</strong> 64-bit value. In the following example, the result is 0xfffff0f0 (4294963440): <code>Transform, OutputVar, BitNot, 0xf0f</code>.</p>

<h3 id="BitAnd">BitAnd</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#bitwise"><code>&amp;</code> operator</a> instead.</p>
<p>Retrieves the result of the bitwise-AND of <em>Number1</em> and <em>Number2</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitAnd, Number1, Number2</pre>
<p>Floating point values are truncated to integers prior to the calculation. In the following example, the result is 0xff00 (65280): <code>Transform, OutputVar, BitAnd, 0xff0f, 0xfff0</code>.</p>

<h3 id="BitOr">BitOr</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#bitwise"><code>|</code> operator</a> instead.</p>
<p>Retrieves the result of the bitwise-OR of <em>Number1</em> and <em>Number2</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitOr, Number1, Number2</pre>
<p>Floating point values are truncated to integers prior to the calculation. In the following example, the result is 0xf0f0 (61680): <code>Transform, OutputVar, BitOr, 0xf000, 0x00f0</code>.</p>

<h3 id="BitXOr">BitXOr</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#bitwise"><code>^</code> operator</a> instead.</p>
<p>Retrieves the result of the bitwise-EXCLUSIVE-OR of <em>Number1</em> and <em>Number2</em>.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitXOr, Number1, Number2</pre>
<p>Floating point values are truncated to integers prior to the calculation. In the following example, the result is 0xff00 (65280): <code>Transform, OutputVar, BitXOr, 0xf00f, 0x0f0f</code>.</p>

<h3 id="BitShiftLeft">BitShiftLeft</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#bitwise"><code>&lt;&lt;</code> operator</a> instead.</p>
<p>Retrieves the result of shifting <em>Number</em> to the left by <em>N</em> bit positions.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitShiftLeft, Number, N</pre>
<p>This is equivalent to multiplying <em>Number</em> by &quot;2 to the <em>N</em>th power&quot;. Floating point values are truncated to integers prior to the calculation. In the following example, the result is 8: <code>Transform, OutputVar, BitShiftLeft, 1, 3</code>.</p>

<h3 id="BitShiftRight">BitShiftRight</h3>
<p class="warning"><strong>Deprecated:</strong> Not recommended for use in new scripts. Use the <a href="../Variables.htm#bitwise"><code>&gt;&gt;</code> operator</a> instead.</p>
<p>Retrieves the result of shifting <em>Number</em> to the right by <em>N</em> bit positions.</p>
<pre class="Syntax"><span class="func">Transform</span>, OutputVar, BitShiftRight, Number, N</pre>
<p>This is equivalent to dividing <em>Number</em> by &quot;2 to the <em>N</em>th power&quot;, truncating the remainder. Floating point values are truncated to integers prior to the calculation. In the following example, the result is 2: <code>Transform, OutputVar, BitShiftRight, 17, 3</code>.</p>

<div id="ToCodePage">
  <h3 id="FromCodePage">FromCodePage / ToCodePage</h3>
  <p><span class="ver">[AHK_L 54+]</span>: Removed. Use <a href="StrPut.htm">StrPut</a>/<a href="StrGet.htm">StrGet</a> instead.</p>
</div>

<h2>Remarks</h2>
<p>Sub-commands that accept numeric parameters can also use <a href="../Variables.htm#Expressions">expressions</a> for those parameters.</p>
<p>If one of the parameters is a floating point number, the following sub-commands will retrieve a floating point number rather than an integer: <a href="#Mod">Mod</a>, <a href="#Pow">Pow</a>, <a href="#Round">Round</a>, and <a href="#Abs">Abs</a>. The number of decimal places retrieved is determined by <a href="SetFormat.htm">SetFormat</a>.</p>
<p>To convert a radians value to degrees, multiply it by 180/pi (approximately 57.29578). To convert a degrees value to radians, multiply it by pi/180 (approximately 0.01745329252).</p>
<p>The value of pi (approximately 3.141592653589793) is 4 times the arctangent of 1.</p>

<h2>Related</h2>
<p><a href="Math.htm">Math Functions</a>, <a href="SetFormat.htm">SetFormat</a>, <a href="../Variables.htm#Expressions">Expressions</a>, <a href="../Variables.htm#Operators">Operators</a>, <a href="StringLower.htm">StringLower</a>, <a href="IfIs.htm">if var is type</a></p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: Get the ASCII code of the letter A.</p>
<pre>Transform, OutputVar, Asc, A</pre>
</div>

</body>
</html>
